Internet Protocol Helper

Purpose

The Internet Protocol Helper (IP Helper) API enables a software developer to retrieve and modify network configuration settings for local computer.

Where Applicable

The IP Helper API is applicable in any computing environment where the TCP/IP network protocol is used and there is a need to programmatically manipulate the TCP/IP configuration. Typical applications would include IP routing protocols, and Simple Network Management Protocol (SNMP) agents.

Developer Audience

The IP Helper API is designed for use by C/C++ programmers. Programmers should also be familiar with TCP/IP networking concepts.

Run-Time Requirements

The IP Helper API is supported on Microsoft® Windows® 98, on Microsoft® Windows NT® version 4.0 with Service Pack 4, and on Windows 2000. Not all of the operating systems support all of the functions. If an IP Helper function on a platform is called that does not support that function, a return value of ERROR_NOT_SUPPORTED is received. For more specific information about which operating systems support a particular function, refer to the Requirements sections in the documentation.

See Also

Routing and Remote Access Service

Overview

General information about the IP Helper API.

Reference

Documentation of the IP Helper functions and structures.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About IP Helper

Internet Protocol Helper (IP Helper) is an API that assists in the network administration of the local computer. You can use IP Helper to programmatically retrieve information about the network configuration of the local computer, and to modify that configuration. IP Helper also provides notification mechanisms to ensure that an application is notified when certain aspects of the network configuration change on the local computer.

Many of the IP Helper functions pass structure parameters that represent data types associated with the Management Information Base technology. The IP Helper functions use these structures to represent various networking information, such as ARP cache entries. Since these structures are also used by the MIB API, they are described in the Management Information Base Reference. Although the IP Helper API uses these structures, IP Helper is distinct from the Management Information Base (MIB) and Simple Network Management Protocol (SNMP).

IP Helper provides capabilities in the following areas:

  • Retrieving Information About Network Configuration
  • Managing Network Adapters
  • Managing Interfaces
  • Managing IP Addresses
  • Using the Address Resolution Protocol
  • Retrieving Information on the Internet Protocol and the Internet Control Message Protocol
  • Managing Routing
  • Receiving Notification of Network Events
  • Retrieving Information About the Transmission Control Protocol and the User Datagram Protocol


Retrieving Information About Network Configuration

IP Helper provides information about the network configuration of the local computer. To retrieve general configuration information, use the GetNetworkParams function. This function returns information that is not specific to a particular adapter or interface. For example, GetNetworkParams returns a list of the DNS servers that are used by the local computer.


Managing Network Adapters

IP Helper provides capabilities for managing network adapters. Use the functions described in the following paragraphs to retrieve information about the network adapters in the local computer.

The GetAdaptersInfo function returns an array of IP_ADAPTER_INFO structures, one for each adapter in the local computer. The GetPerAdapterInfo function returns additional information about a specific adapter. The GetPerAdapterInfo function requires the caller to specify the index of the adapter. To obtain the adapter index from the adapter name, use the GetAdapterIndex function.

Some applications use adapters that receive datagrams, but cannot transmit them. To obtain information about these adapters, use the GetUniDirectionalAdapterInfo function.


Managing Interfaces

IP Helper extends your abilities to manage network interfaces. Use the functions described in the following paragraphs to manage interfaces on the local computer.

Interfaces are related to adapters in that there is a one-to-one correspondence between the interfaces and adapters on a given computer. An interface is an IP-level abstraction, whereas an adapter is a datalink-level abstraction.

The GetNumberOfInterfaces function returns the number of interfaces on the local computer.

The GetInterfaceInfo function returns a table that contains the names and corresponding indexes for the interfaces on the local computer.

The GetFriendlyIfIndex function takes an interface index and returns a backward-compatible interface index, that is, one that uses only the lower 24 bits. This type of index is sometimes referred to as a "friendly" interface index.

The GetIfEntry function returns a MIB_IFROW structure that contains information about a particular interface on the local computer. This function requires the caller to supply the index of the interface.

The GetIfTable function returns a table of MIB_IFROW entries, one for each interface on the computer.

Use the SetIfEntry function to modify the configuration of a particular interface.


Managing IP Addresses

IP Helper can assist you in managing IP addresses that are associated with interfaces on the local computer. Use the functions described in the following paragraphs for IP address management.

The GetIpAddrTable function retrieves a table that contains the mapping of IP addresses to interfaces. More than one IP address may be associated with the same interface.

Use the AddIPAddress function to add an IP address to a particular interface. To remove IP addresses that were previously added using AddIPAddress, use the DeleteIPAddress function.

The IpReleaseAddress and IpRenewAddress functions require the local computer to be using Dynamic Host Configuration Protocol (DHCP). The IpReleaseAddress function releases an IP address that was previously obtained from DHCP. The IpRenewAddress function renews a DHCP lease on a particular IP address. A DHCP lease allows a computer to use an IP address for a specified period of time.


Using the Address Resolution Protocol

You can use IP Helper to perform Address Resolution Protocol (ARP) operations for the local computer. Use the following functions to retrieve and modify the ARP table.

The GetIpNetTable retrieves the ARP table. The ARP table contains the mapping of IP addresses to physical addresses. Physical addresses are sometimes referred to as Media Access Controller (MAC) addresses.

Use the CreateIpNetEntry and DeleteIpNetEntry functions to add or remove particular ARP entries to or from the table. The FlushIpNetTable function deletes all entries from the table.

To create or delete proxy ARP entries, use the CreateProxyArpEntry and DeleteProxyArpEntry functions.

The SendARP function sends an ARP request to the local network.


Retrieving Information on the Internet Protocol and the Internet Control Message Protocol

IP Helper provides information retrieval capabilities that are useful for the network administration of the local computer. The following functions retrieve statistics for the Internet Protocol (IP) and the Internet Control Message Protocol (ICMP). You can also use these functions to set certain configuration parameters for IP.

The GetIpStatistics function retrieves the current IP statistics for the local machine. The GetIcmpStatistics function retrieves the current ICMP statistics.

Use the SetIpStatistics function to enable or disable IP forwarding. This function also makes it possible for you to set the default time-to-live (TTL) for IP datagrams. Alternatively, you can set the TTL by using the SetIpTTL function.


Managing Routing

IP Helper provides features to manage network routing. Use the following functions to manage the IP routing table, and to obtain other routing information.

Retrieve the contents of the IP routing table by making a call to the GetIpForwardTable function. Manipulate specific entries in the IP routing table using the CreateIpForwardEntry, DeleteIpForwardEntry, and SetIpForwardEntry functions. Use the CreateIpForwardEntry function to add a new routing table entry. Use the DeleteIpForwardEntry function to remove an existing entry. The SetIpForwardEntry function modifies an existing entry.

You can also use the router management capabilities of IP Helper to retrieve information about how datagrams are routed over the network. The GetBestRoute function retrieves the best route to a specified destination address. The GetBestInterface function retrieves the index of the interface used by the best route to a specified destination address. Lastly, the GetRTTAndHopCount function retrieves the round-trip time (RTT) and number of hops to a specified destination address.


Receiving Notification of Network Events

Use the following functions to ensure that an application receives notification of certain network events.

Use the NotifyAddrChange function to request notification of any change that occurs in the mapping between IP addresses and interfaces on the local computer.

Similarly, the NotifyRouteChange function enables an application to request notification of any change that occurs in the IP routing table.

The notifications provided by these functions do not specify what changed. They simply specify that something changed. Use other IP Helper functions, such as GetIPAddrTable and GetBestRoute, to determine the exact nature of the change.


Retrieving Information About the Transmission Control Protocol and the User Datagram Protocol

IP Helper makes it possible to access information about network protocols that are used on the local computer. Use the functions described in the following paragraphs to retrieve information about the Transmission Control Protocol (TCP) and User Datagram Protocol (UDP) on the local computer.

The GetTcpStatistics function retrieves the current statistics for TCP. Similarly, the GetUdpStatistics function retrieves the current statistics for UDP.

The GetTcpTable function retrieves the TCP connection table. The GetUdpTable retrieves the UDP listener table.

The SetTcpEntry function enables a developer to set the state of a specified TCP connection to MIB_TCP_STATE_DELETE_TCB.


IP Helper Function Reference

Use the following functions and structures to retrieve and modify configuration settings for the Transmission Control Protocol/Internet Protocol (TCP/IP) transport on the local computer:

  • IP Helper Functions
  • IP Helper Structures
  • IPX Service Table Management


IP Helper Functions

Use the following functions to retrieve and modify configuration settings for the TCP/IP transport on the local computer. These functions are declared in Iphlpapi.h.

  • Alphabetical Listing
  • Categorical Listing


Alphabetical Listing

AddIPAddress

CreateIpForwardEntry

CreateIpNetEntry

CreateProxyArpEntry

DeleteIPAddress

DeleteIpForwardEntry

DeleteIpNetEntry

DeleteProxyArpEntry

EnableRouter

FlushIpNetTable

GetAdaptersAddresses

GetAdapterIndex

GetAdaptersInfo

GetBestInterface

GetBestRoute

GetFriendlyIfIndex

GetIcmpStatistics

GetIfEntry

GetIfTable

GetInterfaceInfo

GetIpAddrTable

GetIpForwardTable

GetIpNetTable

GetIpStatistics

GetNetworkParams

GetNumberOfInterfaces

GetPerAdapterInfo

GetRTTAndHopCount

GetTcpStatistics

GetTcpTable

GetUdpStatistics

GetUdpTable

GetUniDirectionalAdapterInfo

IpReleaseAddress

IpRenewAddress

NotifyAddrChange

NotifyRouteChange

SendARP

SetIfEntry

SetIpForwardEntry

SetIpNetEntry

SetIpStatistics

SetIpTTL

SetTcpEntry

UnenableRouter


Categorical Listing

Adapter Management

GetAdapterIndex

GetAdaptersAddresses

GetAdaptersInfo

GetPerAdapterInfo

GetUniDirectionalAdapterInfo

Address Resolution Protocol

CreateIpNetEntry

CreateProxyArpEntry

DeleteIpNetEntry

DeleteProxyArpEntry

FlushIpNetTable

GetIpNetTable

SendARP

SetIpNetEntry

Interface Management

GetFriendlyIfIndex

GetIfEntry

GetIfTable

GetInterfaceInfo

GetNumberOfInterfaces

SetIfEntry

Internet Protocol and Internet Control Message Protocol

GetIcmpStatistics

GetIpStatistics

SetIpStatistics

SetIpTTL

IP Address Management

AddIPAddress

DeleteIPAddress

GetIpAddrTable

IpReleaseAddress

IpRenewAddress

Network Configuration

GetNetworkParams

Notification

NotifyAddrChange

NotifyRouteChange

Routing

CreateIpForwardEntry

DeleteIpForwardEntry

EnableRouter

GetBestInterface

GetBestRoute

GetIpForwardTable

GetRTTAndHopCount

SetIpForwardEntry

UnenableRouter

Transmission Control Protocol and User Datagram Protocol

GetTcpStatistics

GetTcpTable

SetTcpEntry

GetUdpStatistics

GetUdpTable


AddIPAddress

The AddIPAddress function adds the specified IP address to the specified adapter.

DWORD AddIPAddress(
  IPAddr Address,     // IP address to add
  IPMask IpMask,      // subnet mask for IP address
  DWORD IfIndex,      // index of adapter
  PULONG NTEContext,  // Net Table Entry context
  PULONG NTEInstance  // Net Table Entry Instance
);

Parameters

Address
[in] Specifies the IP address to add to the adapter.
IpMask
[in] Specifies the subnet mask for the IP address.
IfIndex
[in] Specifies the adapter to which to add the address.
NTEContext
[out] Pointer to a ULONG variable that points to the Net Table Entry (NTE) context for this IP address. The caller can later use this context in a call to DeleteIPAddress.
NTEInstance
[out] Pointer to a ULONG variable that points to the NTE instance for this IP address.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The IP address created by AddIPAddress is not persistent. The address exists only as long as the adapter object exists. Rebooting the computer destroys the address, as does manually resetting the network interface card (NIC). Also, certain PnP events may destroy the address.

For information about the IPAddr and IPMask data types, see Win32 Simple Data Types. To convert an IP address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

DeleteIPAddress, GetAdapterIndex


CreateIpForwardEntry

The CreateIpForwardEntry function creates a route in the local computer's IP routing table.

DWORD CreateIpForwardEntry(
  PMIB_IPFORWARDROW pRoute  // pointer to route information
);

Parameters

pRoute
[in] Pointer to a MIB_IPFORWARDROW structure that specifies the information for the new route. The caller must specify values for all members of this structure. The caller must specify PROTO_IP_NETMGMT for the dwForwardProto member of MIB_IPFORWARDROW.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The pRoute parameter is NULL, SetIpFowardEntry is unable to read from the memory pointed to by pRoute, or one of the members of the MIB_IPFORWARDROW structure is invalid.
ERROR_NOT_SUPPORTED | The IP transport is not configured on the local computer.
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

To modify an existing route in the IP routing table, use the SetIpForwardEntry function.

The caller should not specify a routing protocol, for example, PROTO_IP_OSPF, for the dwForwardProto member of the MIB_IPFORWARDROW structure. Routing protocol identifiers are used only to identify route information received through the specified routing protocol. For example, PROTO_IP_OSPF is used only to identify route information received through the OSPF routing protocol.

The dwForwardPolicy member of the MIB_IPFORWARDROW structure is currently unused. The caller should specify zero for this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

DeleteIpForwardEntry, MIB_IPFORWARDROW, SetIpForwardEntry


CreateIpNetEntry

The CreateIpNetEntry function creates an Address Resolution Protocol (ARP) entry in the ARP table on the local computer.

DWORD CreateIpNetEntry(
  PMIB_IPNETROW pArpEntry  // pointer to info for new entry
);

Parameters

pArpEntry
[in] Pointer to a MIB_IPNETROW structure that specifies information for the new entry. The caller must specify values for all members of this structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

DeleteIpNetEntry, MIB_IPNETROW, SetIpNetEntry


CreateProxyArpEntry

The CreateProxyArpEnry function creates a Proxy Address Resolution Protocol (PARP) entry on the local computer for the specified IP address.

DWORD CreateProxyArpEntry(
  DWORD dwAddress,  // IP address for which to act as proxy
  DWORD dwMask,     // subnet mask for IP address
  DWORD dwIfIndex   // interface on which to proxy
);

Parameters

dwAddress
[in] Specifies the IP address for which this computer acts as a proxy.
dwMask
[in] Specifies the subnet mask for the IP address identified by the dwAddress parameter.
dwIfIndex
[in] Specifies the index of the interface on which to proxy ARP for the IP address identified by the dwAddress parameter. In other words, when an ARP request for dwAddress is received on this interface, the local computer responds with the physical address of this interface. If this interface is of a type that does not support ARP, such as PPP, then the call fails.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

DeleteProxyArpEntry, MIB_PROXYARP


DeleteIPAddress

Use the DeleteIPAddress to delete an IP address that was previously added using AddIPAddress.

DWORD DeleteIPAddress(
  ULONG NTEContext  // net table entry context
);

Parameters

NTEContext
[in] Specifies the Net Table Entry (NTE) context for the IP address. This context was returned by the previous call to AddIPAddress.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

AddIPAddress


DeleteIpForwardEntry

The DeleteIpForwardEntry function deletes an existing route in the local computer's IP routing table.

DWORD DeleteIpForwardEntry(
  PMIB_IPFORWARDROW pRoute  // pointer to route information
);

Parameters

pRoute
[in] Pointer to a MIB_IPFORWARDROW structure. This structure specifies information that identifies the route to delete. The caller must specify values for the dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop, and dwForwardPolicy members of the structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The dwForwardPolicy member of the MIB_IPFORWARDROW structure is currently unused. The caller should specify zero for this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateIpForwardEntry, MIB_IPFORWARDROW, SetIpForwardEntry


DeleteIpNetEntry

The DeleteIpNetEntry function deletes an ARP entry from the ARP table on the local computer.

DWORD DeleteIpNetEntry(
  PMIB_IPNETROW pArpEntry  // info identifying entry to delete
);

Parameters

pArpEntry
[in] Pointer to a MIB_IPNETROW structure. The information in this structure specifies the entry to delete. The caller must specify values for at least the dwIndex and dwAddr members of this structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateIpNetEntry, MIB_IPNETROW, SetIpNetEntry


DeleteProxyArpEntry

The DeleteProxyArpEntry function deletes the PARP entry on the local computer specified by the dwAddress and dwIfIndex parameters.

DWORD DeleteProxyArpEntry(
  DWORD dwAddress,  // IP address for which to act as proxy
  DWORD dwMask,     // subnet mask for IP address
  DWORD dwIfIndex   // interface on which to proxy
);

Parameters

dwAddress
[in] Specifies the IP address for which this computer is acting as a proxy.
dwMask
[in] Specifies the subnet mask for the IP address specified by the dwAddress parameter.
dwIfIndex
[in] Specifies the index of the interface on which this computer is supporting proxy ARP for the IP address specified by dwAddress.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateProxyArpEntry, MIB_PROXYARP


EnableRouter

The EnableRouter function turns on IP forwarding on the local computer. EnableRouter also increments a reference count that tracks the number of enable-IP-forwarding requests.

DWORD WINAPI EnableRouter(
  HANDLE *pHandle,
  OVERLAPPED *pOverlapped
);

Parameters

pHandle
Pointer to a handle.
pOverlapped
Pointer to an OVERLAPPED structure. Except for the hEvent member, all members of this structure should be set to zero. The hEvent member should contain a handle to a valid event object. Use the CreateEvent function to create this event object.

Remarks

If the process that calls EnableRouter terminates without calling UnenableRouter, the system will decrement the IP-forwarding reference count as though the process had called UnenableRouter.

Return Values

If the function succeeds, the return value is ERROR_IO_PENDING.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

UnenableRouter, OVERLAPPED, CreateEvent


FlushIpNetTable

The FlushIpNetTable function deletes all ARP entries for the specified interface from the ARP table on the local computer.

DWORD FlushIpNetTable(
  DWORD dwIfIndex  // delete ARP entries for this interface
);

Parameters

dwIfIndex
[in] Specifies the index of the interface for which to delete all ARP entries.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIfTable, GetIpNetTable


GetAdaptersAddresses

[This is preliminary documentation and subject to change.]

The GetAdaptersAddresses functions retrieves the addresses associated with the adapters on the local computer.

DWORD WINAPI GetAdaptersAddresses(
  ULONG Family,
  DWORD Flags,
  PIP_ADAPTER_ADDRESSES pAdapterAddresses,
  PULONG pOutBufLen
);

Parameters

Family
[in] Specifies the address family of the addresses to retrieve. This parameter is one of the following values.
Value | Meaning
AF_INET | Return only IPv4 addresses.
AF_INET6 | Return only IPv6 addresses.
AF_UNSPEC | Return addresses from all address families.

Flags
[in] Specifies the type of the addresses to retrieve. This parameter is a combination of the following values.
Value | Meaning
GAA_FLAG_SKIP_UNICAST | Return unicast addresses.
GAA_FLAG_SKIP_ANYCAST | Return anycast addresses.
GAA_FLAG_SKIP_MULTICAST | Return multicast addresses.

pAdapterAddresses
[in, out] Pointer to a buffer. On successful return, this buffer contains the address information.
pOutBufLen
[out] Pointer to a ULONG variable that specifies the size of the buffer pointed to by pAdapterAddresses.

Return Values

If the function is successful, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer size indicated by the pOutBufLen parameter is too small to hold the adapter information. The pOutBufLen parameter points to the required size.
ERROR_INVALID_PARAMETER | One of the parameters is NULL, the calling process does not have read/write access to the memory pointed to by pOutBufLen, or the calling process does not have write access to the memory pointed to by pAdapterAddresses.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

This information returned by GetAdaptersAddresses includes information for IPv6 interfaces.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.
Library: Use Iphlpapi.lib.

See Also

IP_ADAPTER_ADDRESS, IP_ADAPTER_ADDRESSES


GetAdapterIndex

The GetAdapterIndex function obtains the index of an adapter, given its name.

DWORD GetAdapterIndex(
  LPWSTR AdapterName,  // name of the adapter
  PULONG IfIndex       // index of the adapter
);

Parameters

AdapterName
[in] Pointer to a Unicode string that specifies the name of the adapter.
IfIndex
[out] Pointer to a ULONG variable that points to the index of the adapter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MprConfigGetFriendlyName, MprConfigGetGuidName


GetAdaptersInfo

The GetAdaptersInfo function retrieves adapter information for the local computer.

DWORD GetAdaptersInfo(
  PIP_ADAPTER_INFO pAdapterInfo,  // buffer to receive data
  PULONG pOutBufLen               // size of data returned
);

Parameters

pAdapterInfo
[out] Pointer to a buffer that, , receives a linked list of IP_ADAPTER_INFO structures.
pOutBufLen
[in] Pointer to a ULONG variable that specifies the size of the buffer pointed to by the pAdapterInfo parameter. If this size is insufficient to hold the adapter information, GetAdaptersInfo fills in this variable with the required size, and returns an error code of ERROR_BUFFER_OVERFLOW.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer size indicated by the pOutBufLen parameter is too small to hold the adapter information. The pOutBufLen parameter points to the required size.
ERROR_INVALID_PARAMETER | The pOutBufLen parameter is NULL, or the calling process does not have read/write access to the memory pointed to by pOutBufLen, or the calling process does not have write access to the memory pointed to by the pAdapterInfo parameter.
ERROR_NO_DATA | No adapter information exists for the local computer.
ERROR_NOT_SUPPORTED | GetAdaptersInfo is not supported by the operating system running on the local computer.
Other | If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IP_ADAPTER_INFO


GetBestInterface

The GetBestInterface function retrieves the index of the interface that has the best route to the specified IP address.

DWORD GetBestInterface(
  IPAddr dwDestAddr,     // destination IP address
  PDWORD pdwBestIfIndex  // index of interface with the best route
);

Parameters

dwDestAddr
[in] Specifies the destination IP address for which to retrieve the interface that has the best route.
pdwBestIfIndex
[out] Pointer to a DWORD variable. This variable receives the index of the interface that has the best route to the address specified by the dwDestAddr parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

For information about the IPAddr data type, see Win32 Simple Data Types. To convert an IP address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetBestRoute, MIB_BEST_IF


GetBestRoute

The GetBestRoute function retrieves the best route to the specified destination IP address.

DWORD GetBestRoute(
  DWORD dwDestAddr,             // destination IP address
  DWORD dwSourceAddr,           // local source IP address
  PMIB_IPFORWARDROW pBestRoute  // best route for dest. addr.
);

Parameters

dwDestAddr
[in] Specifies the destination IP address for which to obtain the best route.
dwSourceAddr
[in] Specifies a source IP address. This IP address corresponds to an interface on the local computer. If multiple best routes to the destination address exist, the function selects the route that uses this interface.

This parameter is optional. The caller may specify zero for this parameter.

pBestRoute
[out] Pointer to a MIB_IPFORWARDROW structure. This structure receives the best route for the IP address specified by dwDestAddr.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetBestInterface, MIB_IPFORWARDROW


GetFriendlyIfIndex

The GetFriendlyIfIndex function takes an interface index and returns a backward-compatible interface index, that is, one that uses only the lower 24 bits.

DWORD GetFriendlyIfIndex(
  DWORD IfIndex  // interface index
);

Parameters

IfIndex
[in] Specifies an interface index from which the backward-compatible or "friendly" interface index is derived.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIfEntry, MIB_IFROW


GetIcmpStatistics

The GetIcmpStatistics function retrieves the Internet Control Message Protocol (ICMP) statistics for the local computer.

DWORD GetIcmpStatistics(
  PMIB_ICMP pStats  // pointer to ICMP stats
);

Parameters

pStats
[out] Pointer to a MIB_ICMP structure that receives the ICMP statistics for the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIpStatistics, GetTcpStatistics, GetUdpStatistics, MIB_ICMP


GetIfEntry

The GetIfEntry function retrieves information for the specified interface on the local computer.

DWORD GetIfEntry(
  PMIB_IFROW pIfRow  // pointer to interface entry
);

Parameters

pIfRow
[in] Pointer to a MIB_IFROW structure that receives information for an interface on the local computer. Set the dwIndex member of MIB_IFROW to the index of the interface for which to retrieve information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetNumberOfInterfaces, MIB_IFROW


GetIfTable

The GetIfTable function retrieves the MIB-II interface table.

DWORD GetIfTable(
  PMIB_IFTABLE pIfTable,  // buffer for interface table
  PULONG pdwSize,         // size of buffer
  BOOL bOrder             // sort the table by index?
);

Parameters

pIfTable
[out] Pointer to a buffer that receives the interface table as a MIB_IFTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pIfTable parameter.

On output, if the buffer is not large enough to hold the returned interface table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the returned interface table should be sorted in ascending order by interface index. If this parameter is TRUE, the table is sorted.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIfEntry, GetNumberOfInterfaces, MIB_IFTABLE


GetInterfaceInfo

The GetInterfaceInfo function obtains a list of the network interface adapters on the local system.

DWORD GetInterfaceInfo(
  PIP_INTERFACE_INFO pIfTable,  // buffer to receive info
  PULONG dwOutBufLen            // size of buffer
);

Parameters

pIfTable
[in] Pointer to a buffer that specifies a IP_INTERFACE_INFO structure that contains the list of adapters. This buffer should be allocated by the caller.
dwOutBufLen
[out] Pointer to a DWORD variable. If the buffer pointed to by the pIfTable parameter is NULL, or is not large enough to contain the list of adapters, GetInterfaceInfo receivesthe required size in this DWORD variable.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The dwOutBufLen parameter is NULL, or GetInterfaceInterface is unable to write to the memory pointed to by the dwOutBufLen parameter.
ERROR_INSUFFICIENT_BUFFER | The buffer pointed to by the pIfTable parameter is not large enough. The required size is returned in the DWORD variable pointed to by the dwOutBufLen parameter.
ERROR_NOT_SUPPORTED | This function is not supported on the operating system in use on the local system.
Other | Use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IP_INTERFACE_INFO


GetIpAddrTable

The GetIpAddrTable function retrieves the interface–to–IP address mapping table.

DWORD GetIpAddrTable(
  PMIB_IPADDRTABLE pIpAddrTable,  // buffer for mapping table
  PULONG pdwSize,                 // size of buffer
  BOOL bOrder                     // sort the table
);

Parameters

pIpAddrTable
[out] Pointer to a buffer that receives the interface–to–IP address mapping table as a MIB_IPADDRTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pIpAddrTable parameter.

On output, if the buffer is not large enough to hold the returned mapping table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the returned mapping table should be sorted in ascending order by IP address. If this parameter is TRUE, the table is sorted.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IPADDRTABLE


GetIpForwardTable

The GetIpForwardTable function retrieves the IP routing table.

DWORD GetIpForwardTable(
  PMIB_IPFORWARDTABLE pIpForwardTable,  // buffer for routing table
  PULONG pdwSize,                       // size of buffer
  BOOL bOrder                           // sort the table
);

Parameters

pIpForwardTable
[out] Pointer to a buffer that receives the IP routing table as a MIB_IPFORWARDTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pIpForwardTable parameter.

On output, if the buffer is not large enough to hold the returned routing table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the returned table should be sorted. If this parameter is TRUE, the table is sorted in the order of:
  1. Destination address
  2. Protocol that generated the route
  3. Multipath routing policy
  4. Next-hop address

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IPFORWARDTABLE


GetIpNetTable

The GetIpNetTable function retrieves the IP-to-physical address mapping table.

DWORD GetIpNetTable(
  PMIB_IPNETTABLE pIpNetTable,  // buffer for mapping table
  PULONG pdwSize,               // size of buffer
  BOOL bOrder                   // sort by IP address
);

Parameters

pIpNetTable
[out] Pointer to a buffer that receives the IP-to-physical address mapping table as a MIB_IPNETTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pIpNetTable parameter.

On output, if the buffer is not large enough to hold the returned mapping table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the returned mapping table should be sorted in ascending order by IP address. If this parameter is TRUE, the table is sorted.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IPNETTABLE


GetIpStatistics

The GetIpStatistics function retrieves the IP statistics for the current computer.

DWORD GetIpStatistics(
  PMIB_IPSTATS pStats  // pointer to IP stats
);

Parameters

pStats
[out] Pointer to a MIB_IPSTATS structure thatreceives the IP statistics for the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIcmpStatistics, GetTcpStatistics, GetUdpStatistics, MIB_IPSTATS


GetNetworkParams

The GetNetworkParams function retrieves network parameters for the local computer.

DWORD GetNetworkParams(
  PFIXED_INFO pFixedInfo,  // pointer to buffer to receive data
  PULONG pOutBufLen        // size of buffer
);

Parameters

pFixedInfo
[out] Pointer to a FIXED_INFO structure that receives the network parameters for the local computer.
pOutBufLen
[in] Pointer to a ULONG variable that specifies the size of the FIXED_INFO structure. If this size is insufficient to hold the information, GetNetworkParams fills in this variable with the required size, and returns an error code of ERROR_BUFFER_OVERFLOW.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer size indicated by the pOutBufLen parameter is too small to hold the adapter information. The pOutBufLen parameter points to the required size.
ERROR_INVALID_PARAMETER | The pOutBufLen parameter is NULL, or the calling process does not have read/write access to the memory pointed to by pOutBufLen, or the calling process does not have write access to the memory pointed to by the pAdapterInfo parameter.
ERROR_NO_DATA | No adapter information exists for the local computer.
ERROR_NOT_SUPPORTED | GetNetworkParams is not supported by the operating system running on the local computer.
Other | If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

FIXED_INFO


GetNumberOfInterfaces

The GetNumberOfInterfaces functions retrieves the number of interfaces on the local computer.

DWORD GetNumberOfInterfaces(
  PDWORD pdwNumIf  // pointer to number of interfaces
);

Parameters

pdwNumIf
[out] Pointer to a DWORD variable that receives the number of interfaces on the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIfEntry


GetPerAdapterInfo

The GetPerAdapterInfo function retrieves information about the adapter corresponding to the specified interface.

DWORD GetPerAdapterInfo(
  ULONG IfIndex,                 // index of the interface
  PIP_PER_ADAPTER_INFO pPerAdapterInfo,  // buffer to receive info
  PULONG pOutBufLen              // size of buffer to receive info
);

Parameters

IfIndex
[in] Specifies the index of an interface. GetPerAdapterInfo will retrieve information for the adapter corresponding to this interface.
pPerAdapterInfo
[out] Pointer to an IP_PER_ADAPTER_INFO structure that receives information about the adapter.
pOutBufLen
[in] Pointer to a ULONG variable that specifies the size of the IP_PER_ADAPTER_INFO structure. If this size is insufficient to hold the information, GetPerAdapterInfo fills in this variable with the required size, and returns an error code of ERROR_BUFFER_OVERFLOW.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer size indicated by the pOutBufLen parameter is too small to hold the adapter information. The pOutBufLen parameter points to the required size.
ERROR_INVALID_PARAMETER | The pOutBufLen parameter is NULL, or the calling process does not have read/write access to the memory pointed to by pOutBufLen, or the calling process does not have write access to the memory pointed to by the pAdapterInfo parameter.
ERROR_NOT_SUPPORTED | GetPerAdapterInfo is not supported by the operating system running on the local computer.
Other | If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IP_PER_ADAPTER_INFO


GetRTTAndHopCount

The GetRTTAndHopCount function determines the round-trip time (RTT) and hop count to the specified destination.

BOOL GetRTTAndHopCount(
  IPAddr DestIpAddress,  // destination IP address
  PULONG HopCount,       // returned hop count
  ULONG MaxHops,         // limit on number of hops to search
  PULONG RTT             // round-trip time
);

Parameters

DestIpAddress
[in] Specifies the IP address of the destination for which to determine the RTT and hop count.
HopCount
[out] Pointer to a ULONG variable. This variable receives the hop count to the destination specified by the DestIpAddress parameter.
MaxHops
[in] Specifies the maximum number of hops to search for the destination. If the number of hops to the destination exceeds this number, the function terminates the search and returns FALSE.
RTT
[in] Round-trip time in milliseconds to the destination specified by DestIpAddress.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError to obtain the error code for the failure.

Remarks

For information about the IPAddr data type, see Types. To convert an IP address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetBestInterface, GetBestRoute


GetTcpStatistics

The GetTcpStatistics function retrieves the TCP statistics for the local computer.

DWORD GetTcpStatistics(
  PMIB_TCPSTATS pStats  // pointer to TCP stats
);

Parameters

pStats
[out] Pointer to a MIB_TCPSTATS structure that receives the TCP statistics for the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIcmpStatistics, GetIpStatistics, GetUdpStatistics, MIB_TCPSTATS


GetTcpTable

The GetTcpTable function retrieves the TCP connection table.

DWORD GetTcpTable(
  PMIB_TCPTABLE pTcpTable,  // buffer for the connection table
  PDWORD pdwSize,           // size of the buffer
  BOOL bOrder               // sort the table?
);

Parameters

pTcpTable
[out] Pointer to a buffer that receives the TCP connection table as a MIB_TCPTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pTcpTable parameter.

On output, if the buffer is not large enough to hold the returned connection table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the connection table should be sorted. If this parameter is TRUE, the table is sorted in the order of:
  1. Local IP address
  2. Local port
  3. Remote IP address
  4. Remote port

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_TCPTABLE


GetUdpStatistics

The GetUdpStatistics function retrieves the User Datagram Protocol (UDP) statistics for the local computer.

DWORD GetUdpStatistics(
  PMIB_UDPSTATS pStats  // pointer to UDP stats
);

Parameters

pStats
[out] Pointer to a MIB_UDPSTATS structure that receives the UDP statistics for the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

GetIcmpStatistics, GetIpStatistics, GetTcpStatistics, MIB_UDPSTATS


GetUdpTable

The GetUdpTable function retrieves the User Datagram Protocol (UDP) listener table.

DWORD GetUdpTable(
  PMIB_UDPTABLE pUdpTable,  // buffer for the listener table
  PDWORD pdwSize,           // size of buffer
  BOOL bOrder               // sort the table?
);

Parameters

pUdpTable
[out] Pointer to a buffer that receives the UDP listener table as a MIB_UDPTABLE structure.
pdwSize
[in, out] On input, specifies the size of the buffer pointed to by the pUdpTable parameter.

On output, if the buffer is not large enough to hold the returned listener table, the function sets this parameter equal to the required buffer size.

bOrder
[in] Specifies whether the returned table should be sorted. If this parameter is TRUE, the table is sorted in the order of:
  1. IP address
  2. Port

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_UDPTABLE


GetUniDirectionalAdapterInfo

The GetUniDirectionalAdapterInfo function retrieves information about the unidirectional adapters installed on the local computer. A unidirectional adapter is an adapter that can receive datagrams, but not transmit them.

DWORD GetUniDirectionalAdapterInfo(
  PIP_UNIDIRECTIONAL_ADAPTER_ADDRESS pIPIfInfo,
  PULONG dwOutBufLen
);

Parameters

pIPIfInfo
[out] Pointer to an IP_UNIDIRECTIONAL_ADAPTER_ADDRESS structure that receives information about the unidirectional adapters installed on the local computer.
dwOutBufLen
[out] Pointer to a ULONG variable that receives the size of the structure pointed to by the pIPIfInfo parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IP_UNIDIRECTIONAL_ADAPTER_ADDRESS


IpReleaseAddress

The IpReleaseAddress function releases an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).

DWORD IpReleaseAddress(
  PIP_ADAPTER_INDEX_MAP AdapterInfo  // identifies the adapter
);

Parameters

AdapterInfo
[in] Pointer to an IP_ADAPTER_INDEX_MAP structure that specifies the adapter associated with the IP address to release.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IpRenewAddress


IpRenewAddress

The IpRenewAddress function renews a lease on an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).

DWORD IpRenewAddress(
  PIP_ADAPTER_INDEX_MAP AdapterInfo  // identifies the adapter
);

Parameters

AdapterInfo
[in] Pointer to an IP_ADAPTER_INDEX_MAP structure that specifies the adapter associated with the IP address to renew.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

IpReleaseAddress


NotifyAddrChange

The NotifyAddrChange function causes a notification to be sent to the caller whenever a change occurs in the table that maps IP addresses to interfaces.

DWORD NotifyAddrChange(
  PHANDLE Handle,
  LPOVERLAPPED overlapped
);

Parameters

Handle
[out] Pointer to a HANDLE variable that receives a handle to use in asynchronous notification.
overlapped
[in] Pointer to an OVERLAPPED structure that will notify the caller of any changes in the table that maps IP addresses to interfaces.

Return Values

If the function succeeds, the return value is NO_ERROR if the caller specifies NULL for the Handle and overlapped parameters. If the caller specifies non-NULL parameters, the return value for success is ERROR_IO_PENDING.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

If the caller specifies NULL for the Handle and overlapped parameters, the call to NotifyAddrChange blocks until an IP address change occurs.

If the caller specifies a handle variable and an OVERLAPPED structure, the caller can use the returned handle with the OVERLAPPED structure to receive asynchronous notification of IP address changes. See GetQueuedCompletionStatus and the I/O Completion Ports overview for information about using the handle and OVERLAPPED structure to receive notifications.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

NotifyRouteChange, OVERLAPPED


NotifyRouteChange

The NotifyRouteChange function causes a notification to be sent to the caller whenever a change occurs in the IP routing table.

DWORD NotifyRouteChange(
  PHANDLE Handle,
  LPOVERLAPPED overlapped
);

Parameters

Handle
[out] Pointer to a HANDLE variable that receives a handle to use in asynchronous notification.
overlapped
[in] Pointer to an OVERLAPPED structure that will notify the caller of any changes in the routing table.

Return Values

If the function succeeds, the return value is NO_ERROR if the caller specifies NULL for the Handle and overlapped parameters. If the caller specifies non-NULL parameters, the return value for success is ERROR_IO_PENDING.If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

If the caller specifies NULL for the Handle and overlapped parameters, the call to NotifyRouteChange blocks until a routing table change occurs.

If the caller specifies a handle variable and an OVERLAPPED structure, the caller can use the returned handle with the OVERLAPPED structure to receive asynchronous notification of routing table changes. See GetQueuedCompletionStatus and the I/O Completion Ports overview for information about using the handle and OVERLAPPED structure to receive notifications.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

NotifyAddrChange, OVERLAPPED


SendARP

The SendARP function sends an ARP request to obtain the physical address that corresponds to the specified destination IP address.

DWORD SendARP(
  IPAddr DestIP,     // destination IP address
  IPAddr SrcIP,      // IP address of sender
  PULONG pMacAddr,   // returned physical address
  PULONG PhyAddrLen  // length of returned physical addr.
);

Parameters

DestIP
[in] Specifies the destination IP address. The ARP request attempts to obtain the physical address that corresponds to this IP address.
SrcIP
[in] Specifies the IP address of the sender. This parameter is optional. The caller may specify zero for the parameter.
pMacAddr
[out] Pointer to a ULONG variable. This variable receives the physical address that corresponds to the IP address specified by the DestIP parameter.
PhyAddrLen
[out] Pointer to a ULONG variable. This variable contains the length of the physical address pointed to by the pMacAddr parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

For information about the IPAddr data type, see Win32 Simple Data Types. To convert an IP address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateIpNetEntry, DeleteIpNetEntry, FlushIpNetTable, SetIpNetEntry


SetIfEntry

Use the SetIfEntry function to set the administrative status of an interface.

DWORD SetIfEntry(
  PMIB_IFROW pIfRow  // specifies interface and status
);

Parameters

pIfRow
[in] Pointer to a MIB_IFROW structure. The dwIndex member of this structure specifies the interface on which to set administrative status. The dwAdminStatus member specifies the new administrative status. The dwAdminStatus member can be one of the following values.
Value | Meaning
MIB_IF_ADMIN_STATUS_UP | The interface is administratively enabled.
MIB_IF_ADMIN_STATUS_DOWN | The interface is administratively disabled.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IFROW


SetIpForwardEntry

The SetIpForwardEntry function modifies an existing route in the local computer's IP routing table.

DWORD SetIpForwardEntry(
  PMIB_IPFORWARDROW pRoute  // pointer to route information
);

Parameters

pRoute
[in] Pointer to a MIB_IPFORWARDROW structure that specifies the new information for the existing route. The caller must specify PROTO_IP_NETMGMT for the dwForwardProto member of this structure. The caller must also specify values for the dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop, and dwForwardPolicy members of the structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The pRoute parameter is NULL, or SetIpFowardEntry is unable to read from the memory pointed to by pRoute, or one of the members of the MIB_IPFORWARDROW structure is invalid.
ERROR_NOT_SUPPORTED | The IP transport is not configured on the local computer.
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

To create a new route in the IP routing table, use the CreateIpForwardEntry function.

The caller should not specify a routing protocol, such as PROTO_IP_OSPF, for the dwForwardProto member of the MIB_IPFORWARDROW structure. Routing protocol identifiers are used to identify route information received through the specified routing protocol only. For example, PROTO_IP_OSPF is used to identify route information received through the OSPF routing protocol only.

The dwForwardPolicy member of the MIB_IPFORWARDROW structure is currently unused. The caller should specify zero for this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateIpForwardEntry, DeleteIpForwardEntry, MIB_IPFORWARDROW


SetIpNetEntry

The SetIpNetEntry function modifies an existing ARP entry in the ARP table on the local computer.

DWORD SetIpNetEntry(
  PMIB_IPNETROW pArpEntry  // pointer to new information
);

Parameters

pArpEntry
[in] Pointer to a MIB_IPNETROW structure. The information in this structure specifies the entry to modify and the new information for the entry. The caller must specify values for all members of this structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CreateIpNetEntry, DeleteIpNetEntry, MIB_IPNETROW


SetIpStatistics

The SetIpStatistics function toggles IP forwarding on or off and sets the default time-to-live (TTL) value for the local computer.

DWORD SetIpStatistics(
  PMIB_IPSTATS pIpStats  // new forwarding and TTL settings
);

Parameters

pIpStats
[in] Pointer to a MIB_IPSTATS structure. The caller should set the dwForwarding and dwDefaultTTL members of this structure to the new values. To keep one of the members at its current value, use MIB_USE_CURRENT_TTL or MIB_USE_CURRENT_FORWARDING.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

To set only the default TTL, the caller can also use the SetIpTTL function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IPSTATS, SetIpTTL


SetIpTTL

The SetIpTTL function sets the default time-to-live (TTL) value for the local computer.

DWORD SetIpTTL(
  UINT nTTL  // new default TTL
);

Parameters

nTTL
[in] Specifies the new TTL value for the local computer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The default TTL can also be set using the SetIpStatistics function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_IPSTATS, SetIpStatistics


SetTcpEntry

The SetTcpEntry function sets the state of a TCP connection.

DWORD SetTcpEntry(
  PMIB_TCPROW pTcpRow  // pointer to struct. with new state info
);

Parameters

pTcpRow
[in] Pointer to a MIB_TCPROW structure. This structure specifies information to identify the TCP connection to modify. It also specifies the new state for the TCP connection. The caller must specify values for all the members in this structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

Currently, the only state to which a TCP connection can be set is MIB_TCP_STATE_DELETE_TCB.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

MIB_TCPROW


UnenableRouter

The UnenableRouter function decrements the reference count that tracks the number of enable-IP-forwarding requests. When this reference count reaches zero, UneableRouter turns off IP forwarding on the local computer.

DWORD WINAPI UnenableRouter(
  OVERLAPPED *pOverlapped,
  LPDWORD lpdwEnableCount OPTIONAL
);

Parameters

pOverlapped
Pointer to an OVERLAPPED structure. This structure should be the same as the one used in the call to EnableRouter.
lpdwEnableCount
[out] Pointer to a DWORD variable. This variable receives the number of references remaining.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

Each call that a process makes to UnenableRouter must correspond to a previous call to EnableRouter by the same process. The system returns an error on extraneous calls to UnenableRouter. As a result, a given process is not able to decrement the IP-forwarding reference count for another process. Also, if IP forwarding was enabled by a given process, it cannot be disabled by a different process.

If the process that calls EnableRouter terminates without calling UnenableRouter, the system will decrement the IP-forwarding reference count as though the process had called UnenableRouter.

After calling the UnenableRouter, use the CloseHandle call to close the handle to the event object in the OVERLAPPED structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iphlpapi.h.
Library: Use Iphlpapi.lib.

See Also

CloseHandle, EnableRouter, OVERLAPPED


IP Helper Structures

Use the following structures to retrieve and modify configuration settings for the TCP/IP transport on the local computer:

FIXED_INFO

IP_ADAPTER_ADDRESS

IP_ADAPTER_ANYCAST_ADDRESS

IP_ADAPTER_MULTICAST_ADDRESS

IP_ADAPTER_UNICAST_ADDRESS

IP_ADAPTER_ADDRESSES

IP_ADAPTER_INDEX_MAP

IP_ADAPTER_INFO

IP_INTERFACE_INFO

IP_PER_ADAPTER_INFO

IP_UNIDIRECTIONAL_ADAPTER_ADDRESS


FIXED_INFO

The FIXED_INFO structure contains information that is the same across all the interfaces in a computer.

typedef struct {
  char HostName[MAX_HOSTNAME_LEN + 4] ;
  char DomainName[MAX_DOMAIN_NAME_LEN + 4];
  PIP_ADDR_STRING CurrentDnsServer;
  IP_ADDR_STRING DnsServerList;
  UINT NodeType;
  char ScopeId[MAX_SCOPE_ID_LEN + 4];
  UINT EnableRouting;
  UINT EnableProxy;
  UINT EnableDns;
} FIXED_INFO, *PFIXED_INFO;

Members

HostName[MAX_HOSTNAME_LEN + 4]
Specifies the host name for the local computer.
DomainName[MAX_DOMAIN_NAME_LEN + 4]
Specifies the domain in which the local computer is registered.
CurrentDnsServer
Specifies the current DNS server.
DnsServerList
Specifies the set of DNS servers used by the local computer.
NodeType
Specifies whether the local computer uses dynamic host configuration protocol (DHCP).
ScopeId[MAX_SCOPE_ID_LEN + 4]
Specifies the DHCP scope name.
EnableRouting
Specifies whether routing is enabled on the local computer.
EnableProxy
Specifies whether the local computer is acting as an ARP proxy.
EnableDns
Specifies whether DNS is enabled on the local computer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iptypes.h.

See Also

GetNetworkParams


IP_ADAPTER_ADDRESS

[This is preliminary documentation and subject to change.]

The IP_ADAPTER_ADDRESS structure stores a single address in a linked-list of addresses for a particular adapter.

typedef struct _IP_ADAPTER_ADDRESS {
  struct _IP_ADAPTER_ADDRESS* Next;
  DWORD Length;  // length of this struct
  UINT Lifetime; // in seconds, 0xFFFFFFFF=static
  DWORD Flags;   // see below
  SOCKET_ADDRESS Address;
} IP_ADAPTER_ADDRESS, *PIP_ADAPTER_ADDRESS;

Members

Next
Pointer to the next adapter address structure in the list.
Length
Specifies the length of this structure.
Lifetime
Specifies the lifetime of this address in seconds.
Flags
Specifies flags for this address. Currently, the following value is supported.
Value | Meaning
IP_ADAPTER_ADDRESS_USE_DDNS | Use Dynamic Domain Name Service.

Address
Specifies the address.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetAdaptersAddresses, IP_ADAPTER_ADDRESSES


IP_ADAPTER_ANYCAST_ADDRESS

[This is preliminary documentation and subject to change.]

The IP_ADAPTER_ANYCAST_ADDRESS structure stores a single anycast address in a linked-list of addresses for a particular adapter.

typedef struct _IP_ADAPTER_ANYCAST_ADDRESS {
  union {
    ULONGLONG  _temp;
    struct {
      ULONG Length;
      DWORD Flags;
    }
  };
  struct _IP_ADAPTER_ANYCAST_ADDRESS* Next;
  SOCKET_ADDRESS Address;
  IP_PREFIX_ORIGIN PrefixOrigin;
  IP_SUFFIX_ORIGIN SuffixOrigin;
  IP_DAD_STATE DadState;
  ULONG ValidLifetime;
  ULONG PreferredLifetime;
  ULONG LeaseLifetime;
} IP_ADAPTER_ANYCAST_ADDRESS, *PIP_ADAPTER_ANYCAST_ADDRESS;

Members

Length
Specifies the length of this structure.
Flags
Specifies flags for this address. Currently, the following values are supported.
Value | Meaning
IP_ADAPTER_ADDRESS_DNS_ELIGIBLE | The address is legal to appear in DNS.
IP_ADAPTER_ADDRESS_TRANSIENT | The address is a cluster address and should not be used by most applications.

Next
Pointer to the next adapter address structure in the list.
Address
Specifies the address.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetAdaptersAddresses, IP_ADAPTER_ADDRESSES


IP_ADAPTER_MULTICAST_ADDRESS

[This is preliminary documentation and subject to change.]

The IP_ADAPTER_MULTICAST_ADDRESS structure stores a single multicast address in a linked-list of addresses for a particular adapter.

typedef struct _IP_ADAPTER_MULTICAST_ADDRESS {
  union {
    ULONGLONG  _temp;
    struct {
      ULONG Length;
      DWORD Flags;
    }
  };
  struct _IP_ADAPTER_MULTICAST_ADDRESS* Next;
  SOCKET_ADDRESS Address;
  IP_PREFIX_ORIGIN PrefixOrigin;
  IP_SUFFIX_ORIGIN SuffixOrigin;
  IP_DAD_STATE DadState;
  ULONG ValidLifetime;
  ULONG PreferredLifetime;
  ULONG LeaseLifetime;
} IP_ADAPTER_MULTICAST_ADDRESS, *PIP_ADAPTER_MULTICAST_ADDRESS;

Members

Length
Specifies the length of this structure.
Flags
Specifies flags for this address. Currently, the following values are supported.
Value | Meaning
IP_ADAPTER_ADDRESS_DNS_ELIGIBLE | The address is legal to appear in DNS.
IP_ADAPTER_ADDRESS_TRANSIENT | The address is a cluster address and should not be used by most applications.

Next
Pointer to the next adapter address structure in the list.
Address
Specifies the address.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetAdaptersAddresses, IP_ADAPTER_ADDRESSES


IP_ADAPTER_UNICAST_ADDRESS

[This is preliminary documentation and subject to change.]

The IP_ADAPTER_UNICAST_ADDRESS structure stores a single unicast address in a linked-list of addresses for a particular adapter.

typedef struct _IP_ADAPTER_UNICAST_ADDRESS {
  union {
    ULONGLONG  _temp;
    struct {
      ULONG Length;
      DWORD Flags;
    }
  };
  struct _IP_ADAPTER_UNICAST_ADDRESS* Next;
  SOCKET_ADDRESS Address;
  IP_PREFIX_ORIGIN PrefixOrigin;
  IP_SUFFIX_ORIGIN SuffixOrigin;
  IP_DAD_STATE DadState;
  ULONG ValidLifetime;
  ULONG PreferredLifetime;
  ULONG LeaseLifetime;
} IP_ADAPTER_UNICAST_ADDRESS, *PIP_ADAPTER_UNICAST_ADDRESS;

Members

Length
Specifies the length of this structure.
Flags
Specifies flags for this address. Currently, the following values are supported.
Value | Meaning
IP_ADAPTER_ADDRESS_DNS_ELIGIBLE | The address is legal to appear in DNS.
IP_ADAPTER_ADDRESS_TRANSIENT | The address is a cluster address and should not be used by most applications.

Next
Pointer to the next adapter address structure in the list.
Address
Specifies the address.
PrefixOrigin
Specifies the prefix origin.
SuffixOrigin
Specifies the suffix origin.
DadState
Specifies the Dad state.
ValidLifetime
Specifies the valid lifetime for the address, in seconds.
PreferredLifetime
Specifies the preferred lifetime for the address, in seconds.
LeaseLifetime
Specifies the lease lifetime for the address, in seconds.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetAdaptersAddresses, IP_ADAPTER_ADDRESSES


IP_ADAPTER_ADDRESSES

[This is preliminary documentation and subject to change.]

The IP_ADAPTER_ADDRESSES structure is the "header node" for a linked list of addresses for a particular adapter. This structure can simultaneously be used as part of a linked list of IP_ADAPTER_ADDRESSES structures.

typedef struct _IP_ADAPTER_ADDRESSES {
  union {
    ULONGLONG Alignment
    struct {
        ULONG Length;
        DWORD IfIndex;
    }
  }
  struct _IP_ADAPTER_ADDRESSES* Next;
  char AdapterName[MAX_ADAPTER_NAME_LENGTH + 4];
  PIP_ADAPTER_UNICAST_ADDRESS   FirstUnicastAddress;
  PIP_ADAPTER_ANYCAST_ADDRESS   FirstAnycastAddress;
  PIP_ADAPTER_MULTICAST_ADDRESS FirstMulticastAddress;
} IP_ADAPTER_ADDRESSES, *PIP_ADAPTER_ADDRESSES;

Members

Length
Specifies the length of this structure.
IfIndex
Specifies the index of the interface with which these addresses are associated.
Next
Pointer to the next list of adapter addresses.
AdapterName
Specifies an array of characters that contains the name of the adapter with which these addresses are associated.
FirstUnicastAddress
Pointer to the first unicast adapter address structure in the list of addresses for the adapter specified by AdapterName.
FirstAnycastAddress
Pointer to the first anycast adapter address structure in the list of addresses for the adapter specified by AdapterName.
FirstMulticastAddress
Pointer to the first mulitcast adapter address structure in the list of addresses for the adapter specified by AdapterName.

Requirements

Windows NT/2000 or later: Requires Whistler or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetAdaptersAddresses, IP_ADAPTER_ADDRESS


IP_ADAPTER_INDEX_MAP

The IP_ADAPTER_INDEX_MAP structure pairs an adapter name with the index of that adapter.

typedef struct _IP_ADAPTER_INDEX_MAP {
  ULONG Index;                     // adapter index
  WCHAR Name[MAX_ADAPTER_NAME];    // name of the adapter
} IP_ADAPTER_INDEX_MAP, * PIP_ADAPTER_INDEX_MAP;

Members

Index
Specifies the index of the adapter.
Name[MAX_ADAPTER_NAME]
Pointer to a Unicode string that contains the name of the adapter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Ipexport.h.

See Also

IP_INTERFACE_INFO, GetInterfaceInfo


IP_ADAPTER_INFO

The IP_ADAPTER_INFO structure contains information about a particular network adapter on the local computer.

typedef struct _IP_ADAPTER_INFO {
  struct _IP_ADAPTER_INFO* Next;
  DWORD ComboIndex;
  char AdapterName[MAX_ADAPTER_NAME_LENGTH + 4];
  char Description[MAX_ADAPTER_DESCRIPTION_LENGTH + 4];
  UINT AddressLength;
  BYTE Address[MAX_ADAPTER_ADDRESS_LENGTH];
  DWORD Index;
  UINT Type;
  UINT DhcpEnabled;
  PIP_ADDR_STRING CurrentIpAddress;
  IP_ADDR_STRING IpAddressList;
  IP_ADDR_STRING GatewayList;
  IP_ADDR_STRING DhcpServer;
  BOOL HaveWins;
  IP_ADDR_STRING PrimaryWinsServer;
  IP_ADDR_STRING SecondaryWinsServer;
  time_t LeaseObtained;
  time_t LeaseExpires;
} IP_ADAPTER_INFO, *PIP_ADAPTER_INFO;

Members

Next
Pointer to the next adapter in the list of adapters.
ComboIndex
Reserved.
AdapterName[MAX_ADAPTER_NAME_LENGTH + 4]
Specifies the name of the adapter.
Description[MAX_ADAPTER_DESCRIPTION_LENGTH + 4]
Specifies a description for the adapter.
AddressLength
Specifies the length of the hardware address for the adapter.
Address[MAX_ADAPTER_ADDRESS_LENGTH]
Specifies the hardware address for the adapter.
Index
Specifies the adapter index.
Type
Specifies the adapter type.
DhcpEnabled
Specifies whether dynamic host configuration protocol (DHCP) is enabled for this adapter.
CurrentIpAddress
Specifies the current IP address for this adapter.
IpAddressList
Specifies the list of IP addresses associated with this adapter.
GatewayList
Specifies the IP address of the default gateway for this adapter.
DhcpServer
Specifies the IP address of the DHCP server for this adapter.
HaveWins
Specifies whether this adapter uses Windows Internet Name Service (WINS).
PrimaryWinsServer
Specifies the IP address of the primary WINS server.
SecondaryWinsServer
Specifies the IP address of the secondary WINS server.
LeaseObtained
Specifies the time when the current DHCP lease was obtained.
LeaseExpires
Specifies the time when the current DHCP lease will expire.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iptypes.h.

See Also

GetAdaptersInfo


IP_INTERFACE_INFO

The IP_INTERFACE_INFO structure contains a list of the network interface adapters on the local system.

typedef struct _IP_INTERFACE_INFO {
  LONG NumAdapters;                 // number of adapters in array
  IP_ADAPTER_INDEX_MAP Adapter[1];  // adapter indices and names
} IP_INTERFACE_INFO,*PIP_INTERFACE_INFO;

Members

NumAdapters
Specifies the number of adapters listed in the array pointed to by the Adapter member.
Adapter[1]
Specifies an array of IP_ADAPTER_INDEX_MAP structures. Each structure maps an adapter index to that adapter's name.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Ipexport.h.

See Also

IP_ADAPTER_INDEX_MAP, GetInterfaceInfo


IP_PER_ADAPTER_INFO

The IP_PER_ADAPTER_INFO structure contains information specific to a particular adapter.

typedef struct _IP_PER_ADAPTER_INFO {
  UINT AutoconfigEnabled;
  UINT AutoconfigActive;
  PIP_ADDR_STRING CurrentDnsServer;
  IP_ADDR_STRING DnsServerList;
} IP_PER_ADAPTER_INFO, *PIP_PER_ADAPTER_INFO;

Members

AutoconfigEnabled
Specifies whether auto-configuration is enabled on this adapter.
AutoconfigActive
Specifies whether auto-configuration is active on this adapter.
CurrentDnsServer
Specifies the IP address of the current DNS server for this adapter.
DnsServerList
Specifies the list of possible DNS servers for this adapter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Iptypes.h.

See Also

GetPerAdapterInfo


IP_UNIDIRECTIONAL_ADAPTER_ADDRESS

The IP_UNIDIRECTIONAL_ADAPTER_ADDRESS structure contains the number of unidirectional adapters on the local computer, and the IP addresses that are associated with those adapters.

typedef struct _IP_UNIDIRECTIONAL_ADAPTER_ADDRESS {
  ULONG NumAdapters;
  IPAddr Address[1];
} IP_UNIDIRECTIONAL_ADAPTER_ADDRESS, *PIP_UNIDIRECTIONAL_ADAPTER_ADDRESS;

Members

NumAdapters
Specifies the number of unidirectional adapters on the local computer.
Address[1]
Specifies an array of IPAddr values. These are the IP addresses of the unidirectional adapters on the local computer.

Remarks

For information about the IPAddr data type, see Win32 Simple Data Types. To convert an IP address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Ipexport.h.

See Also

GetUniDirectionalAdapterInfo


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.